gmat (version 0.2.1)

ug-constrained correlation matrices: Simulation of correlation matrices.

Description

Sample correlation matrices, possibly with a zero pattern constrained by an undirected graph.

Usage

port(N = 1, p = 3, d = 1, ug = NULL, zapzeros = TRUE,
  rfun = rnorm, ...)
port_chol(N = 1, p = 3, d = 1, ug = NULL, zapzeros = TRUE, ...)
diagdom(N = 1, p = 3, d = 1, ug = NULL, rfun = rnorm, ...)

Arguments

N

Number of samples.

p

Matrix dimension. Ignored if ug is provided.

d

Number in [0,1], the proportion of non-zero entries in the sampled matrices. Ignored if ug is provided.

ug

An igraph undirected graph specifying the zero pattern in the sampled matrices.

zapzeros

Boolean, convert to zero extremely low entries? Defaults to TRUE.

rfun

Function that generates the random entries in the initial factors, except for port_chol() which uses mh_u() to obtain it.

...

Additional parameters to be passed to rfun or to mh_u().

Value

A three-dimensional array of length p x p x N.

Details

Function port() uses the method described in C<U+00F3>rdoba et al. (2018). In summary, it consists on generating a random matrix Q and performing row-wise orthogonalization such that if i and j are not adjacent in ug, then the rows corresponding to such indices are orthogonalized, without violating previous orthogonalizations and without introducing unwanted independences. The resulting matrix after the process has finished is the cross product of Q.

Function port_chol() uses the method described in C<U+00F3>rdoba et al. (2019), combining uniform sampling with partial orthogonalization as follows. If the graph provided is not chordal, then a chordal cover is found using gRbase::triangulate(). Then uniform sampling for the upper Choleksy factor corresponding to such chordal cover is performed with mh_u(). Finally, it uses partial orthogonalization as port() to add the missing zeros (corresponding to fill-in edges in the chordal cover). The behaviour of this function is the same as port().

We also provide an implementation of the most commonly used in the literature diagdom(). By contrast, this method produces a random matrix M with zeros corresponding to missing edges in ug, and then enforces a dominant diagonal to ensure positive definiteness. Matrices produced by diagdom usually are better conditioned than those by port; however, they typically suffer from small off-diagonal entries, which can compromise model validation in Gaussian graphical models. This is avoided by port.

References

C<U+00F3>rdoba, I., Varando, G., Bielza, C. and Larra<U+00F1>aga, P. A partial orthogonalization method for simulation covariance and concentration graph matrices. Proceedings of Machine Learning Research (PGM 2018), vol. 72, pp. 61 - 72, 2018.

C<U+00F3>rdoba, I., Varando, G., Bielza, C. and Larra<U+00F1>aga, P. Generating random Gaussian graphical models_arXiv_:1909.01062, 2019.

Examples

# NOT RUN {
## Partial orthogonalization
# Generate a full matrix (default behaviour)
port()

# Generate a matrix with a percentage of zeros
port(d = 0.5)
port(d = 0.5, zapzeros = FALSE) # no zero zap

# Generate a random undirected graph structure
ug <- rgraph(p = 3, d = 0.5)
igraph::print.igraph(ug)

# Generate a matrix complying with the predefined zero pattern
port(ug = ug)
port(ug = ug, zapzeros = FALSE) # no zero zap
## Diagonal dominance
# Generate a full matrix (default behaviour)
diagdom()

# Generate a matrix with a percentage of zeros
diagdom(d = 0.5)

# Generate a matrix complying with the predefined zero pattern
igraph::print.igraph(ug)
diagdom(ug = ug)
# }